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1.0  INTRODUCTION 


The  IRMA  (IRis  MAnipulator)  program  was  developed  for  presentation  and  analysis  of  tiuee 
dimensional  distributions  of  physics  data  obtained  from  numerical  simulations.  The  program  has  been 
used  extensively  to  help  understand  and  diagnose  the  complex  output  from  large  simulation  codes 
(POLAR  [LiUey,  et  al.,  1969],  SOCRATES  [Elgin,  1988]  and  MACH  [TauU,  et  al.,  1988])  operated 
by  PHK.  The  IRMA  code  is  currently  implemented  on  a  Silicon  Graphics  IRIS  3030  workstation  v^iicdi 
uses  the  UNIX  operating  system.  A  preliminary  version  has  also  been  brought  up  on  an  IRIS  INDIGO 
minicomputer. 

The  design  considerations  for  IRMA  have  stressed  ease  of  use,  modularity  and  flexibility.  The  prototype 
code  was  configured  by  merging  a  number  of  Silicon  Graphics  demo  programs  and  hence  tiie  graphics 
interface  is  inherently  user  friendly.  The  modularity  of  the  program  allows  the  large  number  of  graphics 
options  to  be  organized  in  a  convenient  and  logical  fashion.  Although  the  program  was  written  to 
handle  data  from  specific  codes,  we  have  tried  to  keep  to  a  general  format  so  that  IRMA  can  be  easily 
accessed  by  other  programs  and  the  graphics  options  are  flexible  enough  to  satisfy  most  plotting 
requirements. 

We  list  below  the  main  features  and  capabilities  of  the  IRMA  program: 
can  read  and  plot  polygon  objects 
can  read  and  plot  trajectories 

can  read  and  plot  2D  image  planes  (compatible  with  IRAF  program) 
can  read  scalar  functions  f(x,y,z)  of  data  defined  on  a  discrete  x,y,z  grid 
can  create  a  dot  pattern  representing  the  grid  nodes  at  (x,y,z) 
can  create  contour  level  surfaces  for  f(x,y,z)  using  polygonal  elements 
can  strip  the  above  contour  surfaces  along  coordinate  lines  for  emphasis 
can  create  planar  slices  through  f(x,y,z)  and  color  code  them 
can  create  speckle  plots  representing  the  local  magnitude  of  f(x,y,z) 
can  set  up  an  arbitrary  observer  viewpoint  with  arbitrary  object  orientation 
can  calculate  integrated  column  densities  for  an  arbitrary  line  of  sight 
accepts  both  asdi  and  binary  node  file  input  and  MSIO  files 

can  save  parameter  files  specifying  the  current  graphics  stiite  for  easy  restoration  and 
continuation  at  a  later  date 
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has  special  window  modes  for  viewing  the  dipping  planes,  for  comparing  objects  side  by  side  and 
a  display  mode  suitable  for  hard  copy  output 

can  do  a  screen  dump  to  an  image  file  which  can  be  later  pasted  to  the  screen  and  manipulated 
with  the  window  manager 

has  a  flexible  color  legend  and  a  choice  of  several  color  and  gr^  maps 

has  text  ports  for  insertion  of  captions  and  labeling  of  units  and  a  primitive  text  editor  for 
modifying  captions 

has  data  scanning  capabilities  for  inspecting  data  at  each  node 

has  a  multi-grid  option  allowing  for  nested  grid  data 

has  a  zbuffer  toggle  for  shadowing  of  hidden  surfaces 

has  an  extensive  set  of  help  files  describing  each  graphics  option 


In  the  following  sections  we  describe  these  features  in  more  detail.  Section  2.0  gives  an  overview  of  the 
basic  user  interface.  The  next  sections  (3.0  to  8.0)  summarize  the  five  program  modules.  Section  9.0 
outlines  the  column  density  algorithm.  A  set  of  appendixes  describes  oth^  features  of  separate  interest 


2.0  THE  USER  INTERFACE 


This  section  contains  an  overview  of  the  basic  IRMA  interface:  how  to  enter  the  program,  how  to 
navigate,  how  to  set  things  and  how  to  exit 

To  execute  IRMA  you  must  first  type  ‘mex*  (not  needed  on  the  INDIGO)  to  turn  on  the  SI  window 
manager  program  and  then  type  ‘irma’  (if  you  are  not  in  the  directory  containing  the  executable  file  irma, 
you  must  set  the  path  to  the  executable).  Tlie  IRMA  program  then  enters  the  input/output  (lO)  module. 
This  is  the  place  to  read  in  any  files  that  you  wish  to  plot  Choose  the  menu  option  #1  to  enter  the 
graphics  mt^ules.  The  first  time  into  graphics,  you  should  be  in  module  3,  in  the  set  up  mode.  The 
various  modules  and  modes  available  and  the  mechanics  of  mouse/keyboard  input  are  described  below. 


MOUSE  INPUT 

The  mouse  allows  continuous  change  of  the  graphics  parameters  which  appear  in  the  status  window 
(upper  left  window  in  setup  mode).  Note  that  the  mouse  selection  of  a  pop  up  menu  option  is  a  two 
step  action:  pressing  down  the  mouse  shows  the  menu,  while  letting  it  up  sdects  the  higMghted  menu 
option. 
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Each  graphics  module  has  its  own  menu  of  options  and  functions.  Some  menu  options  generate 
sub-menus,  but  one  should  never  have  to  go  more  than  one  layer  deep  to  reach  something. 

Although  the  pop  up  menus  are  different  for  each  module,  there  are  a  number  of  common  entries,  v^iidi 
are  listed  below  (the  *  stands  for  any  of  the  five  modules): 


/^/toggles  -  contains  toggles  and  switches  that  can  be  accessed  from  any  motfaile 

/*finfo  -  used  to  generate  information  of  various  sorts.  Print  normally  appears 

lower  left  window  (in  set  up  mode). 

/*/reset_parameters  -  enables  one  to  reset  all  graphics  parameters  for  the  current  module  to 

t'‘ii  original  (on  entering  graphics)  settings. 

/^/modules  -  navigates  between  the  graphics  modules. 

/*/modes  -  switches  between  the  various  graphics  modes. 

/^/return  -  allows  one  to  return  to  the  10  module  or  to  quit  program. 

There  are  two  ways  to  exit  from  the  graphics  modules.  If  you  select  /*/retum/quit  then  the  program  exits 
completely.  All  graphics  parameters  are  lost.  If  you  select  /*/retum,  however,  the  code  returns  bade  to 
the  lO  module  (note  that  to  activate  the  10  module  saeen  on  the  IRIS  3030,  you  must  first  attach  the 
window  with  the  mouse).  From  there  you  can  save  your  graphics  parameters  (option  #11)  or  read  in 
more  data  and  go  back  in  to  graphics.  You  can  also  exit  the  program  directly  from  the  lO  module  by 
selecting  option  #-l. 

The  procedure  to  set  a  graphics  function  parameter  with  the  slider  bar  interfooe  is  given  below: 

1)  To  select  a  graphics  function  press  the  right  mouse  down  to  pop  up  a  graphics  menu,  move 
the  highlight  bar  to  your  choice,  and  then  let  the  mouse  up  to  toggle  on  the  desired  fimetion. 
The  function  name  and  argument  list  should  appear  in  the  status  window  (upper  left  window  in 
set  up  mode) 

2)  Use  the  left  mouse  to  move  the  cursor  and  pick  a  variable  from  the  argument  list  in  the  status 
window.  This  is  done  by  pladng  the  cursor  over  a  number  and  pressing  the  mouse  button  down 
and  up  (the  chosen  variable  will  be  highlighted) 

3)  Use  the  left  mouse  and  cursor  to  pick  and  ‘drag’  the  slider  bar  to  the  desired  value.  If  the 
value  is  off  scale,  the  slider  bar  will  wrap  around  until  it  reaches  the  correct  value. 
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KEYBOARD  INPUT 


The  k^board  allows  one  to  input  discrete  values.  Do  steps  1)  and  2)  above  to  select  the  variable  diat 
is  to  be  changed  Instead  of  step  3)  above  Qrpe  ‘e’  for  enter.  An  enter  prompt  should  appear  in  the 
slider  bar  window.  Type  in  the  desired  numt^r  and  press  return  to  set  the  variable.  The  argument  list 
and  the  slider  bar  will  be  updated  If  you  get  a  ‘bad  number*  message,  hit  ‘escape’  to  ctear  and  enter  the 
number  again.  Blank  spaces  are  not  allowed.  ‘E-format’  is  accepted 

Arguments  can  also  be  picked  from  the  keyboard  (step  2)  above).  First  enter  an  ‘o’  to  open  a  default 
argument  (it  will  be  highlighted).  One  can  then  step  between  args  using  the  ‘1’  and  ‘r*  keys  (left  and 
right).  For  those  functions  with  two  argument  lines,  one  can  jump  to  a  new  argument  line  with  keys  ‘f 
(forward  or  down)  or  ‘b’  (backward  or  up). 

The  k^board  is  always  ready  to  accept  commands,  except  when  in  text  input  mode  (see  ^ipendix  B) 
or  during  number  entry  mode  (see  above).  Pressing  ‘escape’  will  always  restore  the  keyboard  to 
command  mode. 

Hit  /*Anfo/keyboard  to  see  a  list  what  commands  are  available.  There  is  some  redundancy  between  the 
mouse  menu  options  and  the  k^board  commands.  For  example,  one  can  change  modules  from  the 
keyboard  using  the  number  keys.  Or  one  can  change  modes  with  ‘s’,  ‘d’,  ‘c*,  and  ‘x’  k^  (standing  for 
set  up,  display,  clipping  and  compare  modes). 

MODULES  and  MODES 

The  five  modules  implementing  the  graphics  options  are  listed  below: 

1)  module  1  -  sets  the  observers  viewpoint,  using  SI  graphics  functions  ortho,  window,  persp, 
polarview  and  lookat. 

2)  module  2  •  uses  SI  graphics  routines  scale,  translate,  and  rotate  to  manipulate  objects. 
Special  objects  can  be  singled  out  for  independent  transformation. 

3)  module  3  -  creates  graphical  objects  and  modifies  them.  Manages  the  object  list 

4)  module  4  -  creates  images  using  the  column  density  integration  or  loads  in  an  IRAF  image. 
The  ur<ages  can  be  manipulated  and  added  to  the  object  list 

5)  module  5  -  formatting  control  of  various  windows. 

These  graphics  modules  are  described  in  more  detail  in  Sections  4.0  to  8.0  of  this  report 
Graphics  modes  refer  to  user  selectable  window  configurations.  There  are  four  modes  currently  available: 
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1)  Set  up  mode  -  This  is  the  ‘working’  mode.  Thi^  status  and  slider  bar  windows  ^>pear  at  the 
upper  le&  The  main  display  window  is  at  the  right  User  controlled  information  appears  in  die 
box  at  the  lower  left.  The  box  in  the  upper  right  comer  indicates  the  current  nxxhile  and  die 
state  of  the  keyboard. 

2)  Display  mode  •  This  mode  can  be  used  when  an  acceptable  view  has  been  obtained  and 
perhaps  a  hard  copy  is  desired.  Only  the  display  window  appears,  with  all  the  set  up  information 
stripp^  away.  The  zbuffer  or  depth  cueing  options  only  work  in  display  mode  (this  restriction 
applies  only  on  IRIS  3030). 

3)  dipping  mode  -  This  view  shows  the  placement  of  the  clipping  planes,  corresponding  to  the 
current  main  window  view.  For  convenience,  a  compressed  view  of  the  display  window  appears 
at  the  upper  right.  This  mode  can  be  used  to  clarify  the  clipping  plane  configuradoiL 

4)  Compare  mode  -  Allows  one  to  show  selected  (from  the  object  list)  objects  side  by  side  for 
direct  comparison.  Uses  /m3/select_objects/window_l  or  2  to  fill  the  two  windows. 

The  current  color  map  can  be  displayed  (in  set  up  mode)  by  going  to  module  3  and  toggling 
/in3/color_map/show_map.  If  the  color  map  is  bad  (e.g.  after  a  system  crash)  it  can  be  restored  to  the 
standard  rainbow  map  by  selecting  /m3/color_map/normal_map. 

There  exists  an  irmafiles/help  subdirectory  with  detailed  information  on  most  of  the  IRMA  options  and 
functions.  This  directory  contains  many  small  files.  The  names  of  the  help  files  are  chosen  to  be  similar 
to  the  functions  they  describe,  usually  corresponding  to  the  pop  up  menu  entry  string.  Use  Unix 
commands  Is  and/or  grep  to  find  the  help  you  need. 
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3.0  INPUT/OUTPUT  FILES  GO  MODULE) 


On  entering  the  IRMA  program  the  input/output  (lO)  module  menu  appears.  This  menu  is  used  mainly 
to  read  and  write  files.  There  are  presently  six  types  of  files  supported: 

1)  surface  polygon  file  -  contains  a  list  of  color  coded  polygons  describing  some  object  e.g.  the 
space  shuttle.  Format  is  compatible  with  POLAR/SHONTiyNPLDIS  output 

2)  asdiA^inary  node  data  files  -  A  complete  set  of  tools  exist  for  asdi  read/write  and  binary 
read/write.  They  are  compatible  with  MACH  and  SOCRATES  output 

3)  MSIO  node  data  files  •  these  are  ‘indexed  sequential  binary’  fil^,  modeled  on  the  CYBER 
mass  storage  routines. 

4)  trajectory  files  -  contains  particle  trajectory  step  data.  The  format  is  compatible  with 
POIAR^HONTL/NPLDIS  output 

5)  IRAF  image  files  -  two  dimensional  images  written  by  the  IRAF  program.  These  files  can 
also  be  written  by  MACH. 

6)  graphics  parameter  files  -  allows  one  to  save  the  graphics  parameters  from  an  IRMA 
ses'icTi 


Column  density  images  can  also  be  written  out  in  asdi  node  file  format  (2  above).  These  files  can  be 
read  by  an  auxUiaty  code  and  converted  to  SUATEK  or  MACHCON  format  for  black  and  ti^te  contour 
plots. 

When  reading  a  file,  IRMA  will  ask  for  the  file  name.  If  the  file  is  not  in  the  current  directory,  this 
name  should  include  the  path.  After  the  read  in  is  completed,  IRMA  always  prints  a  little  information 
to  help  verify  that  the  file  was  read  correctly.  This  is  usually  the  minimum  and  maximum  from  a  scan 
of  the  data  that  was  read. 

Polygon  files: 

The  polygon  file  is  asdi  and  has  a  very  simple  format.  It  consists  of  a  list  of  pofygons.  Each  polygon 
is  specified  by  a  card  giving  the  number  of  vertices  and  the  value  at  each  vertex,  followed  one  card 
for  each  vertex  with  its  x,y,z  coordinates.  For  example,  an  equilateral  triangle  lying  in  the  x-y  plane,  with 
node  values  -2.5,  0.0,  2.5  would  be  given  by  the  cards: 

3  -2.5  0.  2.5  =  number  of  vertices  and  values  at  each  one 
-1.  0.  0.  =  x,y,z  of  vertex  1 

1.  0.  0.  =  x,y,z  of  vertex  2 

0.  -1.  0.  =  x,y,z  of  vertex  3 
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Polygon  vertices  should  always  be  drawn  in  the  counter  clockwise  direction,  as  seen  from  positive  z.  If 
the  /m3/modify_obiects/solid  toggle  is  on,  the  polygon  will  be  drawn  in  one  color  using  the  value  of  the 
first  vertex.  If  the  ^a3/modify_objects/gouraud  option  is  on,  the  polygon  will  be  gouraud  shaded  Le.  the 
colors  will  be  linearly  ramped  between  the  vertices.  Polygon  files  are  read  in  by  subroutine  ieadob.l 

Node  data  files: 

The  node  data  files  also  have  a  simple  format  It  consists  of  some  header  lines  and  then  columns  of  data 
as  indicated  below: 

N  =  nu.aber  of  input  parameters  (zero  is  expected) 

M  number  of  variables  in  this  file 

...followed  by  one  caption  string  card  for  each  of  the  M  variables 

NX  NY  NZ  number  of  grid  nodes  in  x,y  and  z  directions 

...followed  by  x  coordinates  list 

...followed  by  y  coordinates  list 

...foUowed  by  z  coordinates  list 

valuel  value2  vaiue3  ...  -  up  to  M  columns  of  data 

...more  columns  of  data 

For  the  columns  of  data  the  x  index  runs  latest,  then  y,  then  z.  The  value  of  N  can  be  set  non-zero  to 
maintain  compatibility  with  old  files,  but  currently  no  input  parameters  are  passed  to  IRMA.  Node  files 
are  read  in  by  subroutine  readab.f. 

MSIO  files: 

MSIO  files  cany  the  same  data  as  the  node  data  files  above.  The  advanta^  of  using  MSIO  files  are: 

a)  they  are  binary,  hence  smaller  (by  -1/3) 

b)  th^  are  quicker  to  read  in 

c)  they  have  a  ‘kQ^  structure  allowing  sub-file  organization 

d)  they  support  multi-grid  data 

e)  they  are  compatible  across  different  machines 

A  disadvantage  of  the  MSIO  files  is  that  there  is  considerable  set  up  work  needed  to  use  them  le.  the 
routines  to  create  these  files  must  be  constructed.  A  set  of  prototype  routines  to  be  used  for  developing 
this  capability  are  located  in  a  IRMA  subdirectory  called  irmafile^mstools.  MSIO  files  are  read  in  by 
subroutine  readin.£. 

Trajectory  files: 

The  trajectory  files  contains  a  sequence  of  trajectory  step  data  of  the  form: 

X  y  z  color  =  x,y,z  coordinates  and  color  index 
...followed  by  more  cards  of  same  form 
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The  color  variable  is  a  function  of  the  track  coordinates  ^ch  can  be  used  to  describe  local  conditions, 
e.g.,  the  electrostatic  potential  at  each  time  step.  The  trajectoiy  is  plotted  in  increments  of  two.  That 
is,  a  straight  line  is  drawn  from  point  1  to  point  2,  from  point  3  to  4,  from  point  S  to  6,  etc.  No  line  is 
drawn  between  point  2  and  3,  4  and  S,  etc.  This  is  the  SCUBED  format  and  is  designed  to  follow 
multiple  independent  tracks.  If  a  single  continuous  track  is  desired  the  connecting  points  must  be  equal 
i.e  point  2  equals  point  3,  point  4  equals  S  and  so  on.  When  drawing  the  track,  IRMA  adds  a  smaU 
!^te  line  segment  on  the  forward  end  to  indicate  the  direction  of  the  track.  Trajectory  files  are  read 
in  by  subroutine  nrtraj.f. 

IRAF  image  files: 

The  IRAF  image  files  contain  f(x,y)  data  written  in  FITS  format.  There  is  a  set  of  header  cards  and  tiben 
a  linear  string  of  data  values.  Consult  the  IRAF  documentation  for  details  [NO AO,  1967]. 

While  reading  these  files,  IRMA  will  prompt  for  information.  For  IRAF  files  this  is  the  number  of 
colunms  of  data  and  the  format,  which  can  be  read  off  the  header  cards.  For  files  written  by  MACH, 
one  can  also  input  information  on  the  image  boundaries.  IRAF  image  files  are  read  in  by  subroutine 
readim.f. 

Graphics  parameter  files: 

The  graphics  parameter  files  are  written  by  IRMA  from  the  lO  module.  The  purpose  of  these  files  is 
to  save  foe  final  graphics  parameters  from  an  IRMA  session.  When  you  return  at  a  later  date  you  can 
read  this  file  and  restore  foe  graphics  parameters  to  foe  original  settings.  Reading  a  parameter  file  over 
writes  any  existing  parameter  settings. 

On  the  INDIGO  version  of  IRMA  we  have  added  an  option  to  read  foe  SOCRATES  binaiy  files 
directty.  This  feature  bypasses  the  need  to  transfer  data  by  means  of  intermediate  files.  By  choosing  the 
lO  module  option  #11,  one  enters  a  sub-menu  of  IRMA  and  interactively  selects  the  dmired  variables 
from  foe  SOCRATES  restart  file.  Plots  can  be  made  and  then  another  variable  selected.  This  provides 
a  fast  and  convenient  way  to  interrogate  a  SOCRATES  nm. 
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4.0  OBSERVER  VIEWPOINTS  (MODULE  1) 


Module  1  sets  the  observers  viewpoint,  using  SI  graphics  functions  ortho,  window,  posp,  polarview  and 
lookat 

For  a  full  description  of  the  above  SI  graphics  functions  see  their  documentatioa  Briefly,  the  fiinctions 
ortho,  window  and  persp  define  the  observers  view  by  means  of  clipping  planes.  For  ortho,  Much  is  the 
non-perspective  case,  there  are  six  orthogonal  clipping  planes  forming  a  parallelepiped  Mudi  frames  die 
view.  For  the  perspective  views,  window  and  persp,  the  clipping  planes  form  a  viewing  pyramid  with  die 
eye  at  the  vertex.  The  window  function  is  the  same  as  persp,  but  allows  more  flexibiliQr  in  setting  the 
(Upping  planes. 

To  activate  these  transformations  select  menu  option  /ml/ortho/window/persp  and  choose  the  desired 
fimction.  In  order  to  facilitate  usage  of  these  graphics  functions,  we  have  defined  some  combination 
moves.  These  allow  one  to  tie  together  arguments  in  the  argument  list  in  such  a  way  as  to  effidently 
produce  effects  that  are  needed  frequently.  These  combinations  are  listed  below: 

1+r  »  move  left  and  right  dipping  planes  together  (with  constant  difference)  to 

produce  a  horizontal  shift 

b+t  -  move  bottom  and  top  dipping  planes  together  to  produce  a  vertical  shift 

n+f  >=  move  near  and  for  clipping  planes  together  to  shift  the  clipping  span 

n-f  =  move  near  and  far  dipping  planes  in  opposition  to  expand  or  narrow  the 

dipping  span 

zoom  =  move  the  clipping  planes  in  such  a  way  as  to  produce  a  zoom.  This  is  done 
differently  for  each  function: 

ortho  -  all  six  clipping  planes  are  moved  in  opposition 
Avindow  -  the  front  window  sides  are  moved  in  opposition 
persp  -  not  needed  (the  fov  variable  does  a  zoom) 

When  one  chooses  one  of  these  combinations,  a  message  appears  to  the  right  in  the  status  window 
indicating  which  variable  to  pick  in  order  to  move  the  arguments  together. 

There  are  also  some  conversion  options  to  translate  one  view  to  another  e.g.  use  ortho/window  to  go 
from  window  to  ortho.  These  wUl  only  give  an  approximate  correspondence,  since  exact  matching  is  not 
always  possible. 

The  polarview  and  lookat  functions  pK>sition  the  observers  eye  at  a  specified  location.  The  polarview 
function  puts  the  observer  on  the  surfece  of  a  sphere,  looking  towards  the  origin.  The  lookat  fimction 
puts  the  eye  at  an  arbitrary  position  and  with  an  arbitrary  line  of  sight  It  is  thus  more  general  than 
polarview.  However,  polarview  has  been  found  adequate  for  most  purposes  and  lookat  has  only  been 
infrequently  used.  To  modify  these  functions  choose  menu  option  /ml/polarview/lookat 
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There  are  menu  options  to  look  directly  down  the  x,  y  and  z  axis.  These  woilc  by  changing  the  angle 
arguments  to  polarview.  They  can  be  used  to  quickly  look  at  an  object  from  aU  sides.  These  options 
over  write  the  current  polarview  parameters. 

The  view  clipping  menu  option  brings  up  a  sub-menu  that  can  be  used  to  modify  the  two  views  of  die 
dipping  mo^  One  can  toggle  between  perspective  and  orthogonal  views,  zoom,  rotate  and  diange  die 
observer  distance. 

Typically  one  would  like  to  frame  the  grid  data  as  dosely  as  possible,  for  example  when  cakailating 
oolunm  densities.  This  can  be  done  by  first  creating  the  grid  nodes  object  and  then  using  the  dipping 
mode  and  the  module  1  graphics  fimctions  to  set  the  planes  at  the  grid  boundaries. 


5.0  OBJECT  TRANSFORMATIONS  (MODULE  2) 


Module  2  uses  SI  graphics  routines  scale,  translate,  and  rotate  to  manipulate  objects.  One  can  think  of 
these  transformations  as  active  (observer  fixed,  object  moves)  as  opposed  to  the  module  1  viewing  optkms 
which  can  be  thought  of  as  passive  (observer  moves,  object  fixed).  If  one  just  wants  to  inspect  an  object, 
this  module  can  be  a  little  easier  to  use  e.g.  the  rotations  are  done  directly  around  each  of  the  three 
coordinate  axis  rather  than  in  terms  of  the  more  complicated  azimuth,  inclination  and  twist  angles.  The 
total  viewing  matrix  will  be  the  product  of  the  observer  transformations  of  module  1  and  the  object 
transformations  (if  any)  of  module  2. 

The  translate,  rotate  and  scale  transformations  work  as  described  by  SI: 

/m2/translate:  moves  objects  pmallel  to  the  x,  y  or  z  axis 

/m2/rotate:  rotates  objects  around  the  x,  y  or  z  axis  (units  are  degrees/10) 

/m2/scale:  shrinks,  expands  or  mirrors  objects  along  each  of  the  x,  y  or  z  axis 

In  IRMA  we  have  defined  an  additional  function,  zoom,  which  scales  objects  equally  in  the  z,y,z 
directions.  One  can  combine  these  transformations  to  create  more  complex  transformations.  The  order 
is  important  Rotates  are  done  before  translates  in  the  order  x,  then  y,  then  z. 

The  main  complication  in  module  2  is  the  definition  of  special  objects.  This  allows  one  to  treat  certain 
objects  differently  than  others  with  respect  to  rotate,  translate  and  scaling.  This  feature  can  be  used  to 
m^  adjustments  for  input  coming  from  different  programs.  For  example,  if  a  polygon  model  of  ffie 
space  shuttle  was  created  by  one  program,  say  POLAR,  for  use  with  the  data  from  another  program,  say 
SCXRATES,  it  might  be  necessary  to  introduce  a  scale  factor,  translation,  and/or  a  rotation  to  properly 
place  and  orient  the  POLAR  shuttle  in  the  SOCRATES  grid  space.  We  can  do  this  by  defining  die 
shuttle  to  be  special;  it  can  then  be  transformed  independently  of  other  objects. 


10 


The  two  IRMA  functions  that  handle  special  ob^cts  aie: 

/nt2/select_special  -  This  is  a  switdi  that  toggles  on/o£f  the  special  object  transformatioos 

for  selected  objects.  It  has  no  eSecX  if  a  special  transfonnation  has  not 
previously  been  defined  for  the  object  The  list  option  summarizes  die 
current  status. 

/m2/modify_special  -  This  switch  must  be  turned  on  before  an  a  selected  object  can  be 

modified.  The  rotate,  translate  and/or  scaling  transformations  can  then 
be  set  The  status  window  should  say  wiuch  object  is  ready  for  dumge, 
and  give  a  summary  of  all  the  argument  values.  The  arguments  cannot 
be  changed  at  this  point  To  do  this  one  must  pidc  out  die  qipropriate 
transformation  fixim  the  menu  options  and  set  it  in  the  normal  wqr. 

By  default  the  transformations  of  module  2  apply  to  all  graphical  objects  in  the  object  l»t  and  to  make 
a  certain  object  special  one  would  do  the  following: 

a)  use  modify_special  to  enable  the  object  as  special 

c)  choose  a  transformation,  say  rotate,  and  set  the  angles 

If  one  uses  /m2/se]ect_special_objects  to  toggle  off  the  special  status,  the  object  will  revert  to  normal 
status.  Select  /m2/modify_special/none  to  reset  module  2  so  that  any  subsequent  transformations  will 
apply  to  aU  objects. 

The  action  of  the  module  2  transformations  can  be  observed  by  using  the  IRMA  dipping  mode.  \^iew 
any  object  (e.g.  the  x,y,z  axis)  and  vary  the  translate,  rotate,  or  scale  parameters.  The  object  will  respond 
but  the  dipping  planes  will  remain  fixed.  This  is  in  contrast  to  the  viewing  transformations  of  module 
1,  which  change  the  clipping  planes,  with  the  object  held  fixed. 

The  special  object  settings  are  written  to  the  IRMA  parameter  file  so  th^  can  be  recovered  in 
subsequent  runs. 

Note  that  the  /toggles/socrates  switch  uses  the  spedal  objects  option.  This  switch  sets  the  graphics 
parameters  up  for  a  reasonable  first  look  at  SOCRATES  data.  It  assumes  that  the  shuttle  object  has 
been  read  in  from  the  lO  module  and  it  makes  this  object  spedal.  This  can  lead  to  some  confiision  if 
you  toggle  socrates  on,  without  reading  in  the  shuttle  model. 
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6.0  CREATE  AND  MANIPULATE  OBJECTS  (MODULE  3) 


Module  3  is  used  to  create  graphical  objects,  to  modify  them,  aod  to  manage  the  object  list  It  alto  can 
be  used  to  manage,  the  grid  list  if  more  than  one  grid  is  read  in.  The  color  map  options  are  also  in  diis 
modute. 

The  module  builds  graphical  objects  of  various  types,  based  on  grid  node  data  that  has  been  previousfy 
read  in.  The  module  3  pop  up  menu  options  t^t  actually  create  objects  are  marked  with  an  asterisk. 
Eadi  object  that  is  created  is  automatically  placed  in  the  object  list  A  list  of  die  currentfy  availaUe 
objects  is  given  below. 

(CONTOURS  •  these  are  2D  surfaces  of  constant  value.  Use  the /in3Aet_leveb  fiinction  to  dioose  iq> 
to  three  surface  levels  per  object  The  algorithm  builds  a  polynomial  object  by  finding 
the  intersections  of  the  specified  level  value  with  the  volume  cell  boundary  lines  and  dien 
constructing  triangles  connecting  to  the  intersections  and  to  a  common  cell  midpoint 

SLICES  -  these  are  2D  surfaces  on  a  planar  cut  through  the  data.  Use  die  /m3Aet_nodes 
function  to  choose  the  ij,k  grid  nodes.  For  example,  selecting  j  -  8  would  specify  die 
plane  defined  by  y(8)  »  constant  The  default  slice  format  is  the  wire  frame.  Use 
/m3/modify_objects/gouraud  to  produce  a  color  coded  slice. 

CLOUDS  •  these  are  speckle  plots  with  random  pixel  dot  density  rqiresenting  die  data  magnitiide 
(assumed  >  0).  For  example,  this  has  been  used  to  d^kt  pardde  number  densify 
distributions.  The  number  of  (kits  put  in  volume  cell  i  is  Uj  «  c*£(x^,z)*dV  where  c  is 
a  normalization  constant  set  so  that  2  nj  «  n,  where  n  is  user  input  (default  -•  KXXX)). 
Use  /m3/set_cloud  to  modify  the  cloud  parameters. 

GRIDS  •  this  is  a  dot  pattern  representing  the  grid  nodes.  The  options  are  a  sin|^  vdiite  dot 
giving  the  nods  location  or  a  colored  dot  (actually  a  cluster  of  7  closely  spaced  dots) 
coded  according  to  the  data  value  at  the  no^.  Use  /m3/modifyj>bjects/oolOT_or_'Miite 
to  switch  between  these  two  options. 

Once  an  object  has  been  placed  in  the  object  list,  it  may  be  toggled  on  and  off  using  /m3Aelect_objects. 
One  can  remove  the  last  object  (only)  from  the  list  using  /m3/deIete_last_object  There  are  a  number 
of  other  options  that  may  be  used  to  manipulate  objects  selectively  i.e.  governed  by  selectjobjects,  whidi 
are  described  below. 

/m3/modify_objects  -  diange  from  wire  frame  to  solid,  gouraud  shade  and  other  options.  An 
automatic  redraw  is  done. 

/m3/keep/cut  •  allows  one  to  remove  a  selected  volume  region  from  the  polygon  draw  loop. 

One  can  remove  all  polygons  outside  a  specified  region  (a  Imep)  or  inside  a 
region  (a  cut). 


/mS^trip  -  allows  ooe  to  redraw  a  polygon  surface  contour  using  only  the  planar 

projection  in  one  of  the  coordinate  directioos.  These  stripped  pc^gcms  are 
drawn  with  double  width  lines  to  enhance  visibility.  The  strip^  objects  do  not 
appear  in  the  object  list,  they  have  their  own  sub-menu  for  selecting  on  and  off 


/mS/redraw  -  Sometimes  it  is  desirable  to  redraw  a  polygon  object  This  might  be  done  afim 

a  color  mapping  change,  after  turning  on  a  keep  or  cut  or  for  some  other 
reason. 

/m3/oenter  -  Sometimes  it  is  easier  to  manipulate  an  object  if  it  is  centered  widi  respect  to 

the  origin.  This  switch  enables  one  to  center  and  un-oenter  selected  objects. 
The  centering  transformation  is  based  on  the  fost  object  that  was  read  in  by  die 
10  module. 

The  foi3/select_grid  option  allows  one  to  pick  out  individual  grids  for  display  and  analysis.  Each  node 
data  set  that  is  read  in,  goes  into  a  separate  grid  (th^r  may  be  identical).  &  switching  grids  enables  one 
to  choose  between  different  data  sets.  The  /m3/5el^ .jrid  option  can  also  be  used  in  combinatkm  with 
the  nesting  function  to  treat  multi-grid  input  (see  Appendix  D).  The  nesting  function  applies  to  all 
grkh  that  are  selected  on.  It  partitions  the  volume  space  in  such  a  way  that  any  vcdume  element  is 
covered  only  by  the  highest  imbedded  grid.  If  toggled  on,  the  nesting  function  is  us^  in  any  subsequent 
object  creations. 

The  /m3/lin_log  switch  allows  one  to  convert  the  node  data  to  loglO.  This  may  stiU  have  some  glitdbes. 
The  /m3/oolor_map  option  allows  one  to  control  the  color  map  and  the  color  legend  (see  ^qjpendiz  A). 


7.0  CREATE  AND  MANIPULATE  IMAGES  (MODULE  4) 


Module  4  enables  one  to  handle  images.  Images  differ  from  objects  in  two  main  ways. 

a)  they  are  two  dimensional  planes  holding  projected  image  data 

b)  th^  are  drawn  on  the  ba^  clipping  planes,  using  the  current  view  parameters 

Images  can  be  promoted  to  objects  in  the  object  list  (using  the  /m4Aunage_to_object  option).  But  images 
are  generally  more  transitory  than  objects  i.e.  if  the  observer  view  is  changed,  then  the  image  will  no 
longer  be  lined  up  on  the  back  clipping  plane,  and  a  new  image  should  probably  be  created. 

The  two  main  image  building  options  are: 

/m4/create_coluinns  -  This  enables  one  to  aeate  column  density  images  Ity  integrating  through  the 
input  grid  node  data.  See  Section  9.0  for  column  density  details. 

/m4/load_IRAF  -  Any  IRAF  image  file  that  was  read  in  from  the  lO  module  can  be  loaded  in 
here. 
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When  a  new  image  is  created,  it  overwrites  any  previous  one,  so  that  there  is  only  one  current  image. 


The  resolution  lines  defining  a  column  image  may  be  viewed  using  the  /m4^nage_tines  option.  Eadi 
image  line  is  then  surrounded  a  colored  coded  box  The  color  index  is  based  on  the  column  density 
value  for  a  ray  going  through  the  center  of  the  box  There  are  also  options  for  displ^ing  sdid  or 
gouraud  shaded  boxes. 

The  IRAF  images  can  be  modified  using  the  options  in  set_IRAF.  The  default  resolution  is  fiiat  of  file 
input  data  file,  but  one  can  also  change  it  (with  /m4/5et_IRAF)  so  that  the  column  density  resolution 
setting  is  used  instead,  in  which  case  one  gets  interpolated  data  values.  One  can  also  position  file  image 
with  respect  to  arbitrary  boundary  limits  (one  must  specify  the  true  image  boundaries  at  read  in  time). 
For  example,  the  image  files  written  by  MACH  for  the  velocity  space  distribution  fimction,  have  differing 
angle  boundaries,  which  can  be  lined  up  with  respect  to  a  common  range  say,  0  to  180  d^rees.  Ties  and 
numbers  can  be  printed  to  make  the  boundaries  clearer. 

The  color  legend  for  images  is  separate  from  that  for  objects.  It  will  change  automatically  from  fiie 
object  legend  to  file  image  legend  if  one  builds  column  densities  or  loads  in  an  IRAF  image.  One  can 
use  /m4fimage_legend  to  choose  one  of  two  scale  modes  which  are: 

1)  CALC  -  The  natural  scale.  Here  the  min  and  max  are  calculated  by  a  scan  of  file 

image  data  values. 

2)  SET  •  An  imposed  scale.  Here  one  sets  the  min  and  max  with  the  mouse. 

One  would  typically  use  CALC  to  first  generate  the  limits.  Then  SET  might  be  used  to  round  off  fiie 
end  points  or  to  set  a  common  scale  for  subsequent  images.  Any  data  that  fedls  off  the  end  of  the  scale 
retains  the  color  of  the  end  point. 

The  units  for  the  image  legend  are  arbitrary.  They  can  be  modified  for  column  density  images  (see 
Section  9.0).  Press  V  for  a  display  of  the  current  units  above  the  legend. 

If  you  have  more  than  one  IRAF  image  to  view,  read  in  the  first  one  and  go  into  graphics,  create  it  and 
put  it  into  the  object  list  using  /m4fimage_to_object.  Then  return  to  the  lO  module,  read  in  the  next 
image  and  go  back  to  graphics.  Any  number  of  images  can  be  assembled  this  way. 

Two  images  may  be  viewed  side  by  side  using  the  compare  mode.  The  procedure  for  setting  up  this  view 
is  given  below: 

1)  pick  the  compare  mode  to  view  the  two  windows 

2)  create  the  fiint  image  and  use  /m4fimage_to_objects  to  place  it  in  the  object  list  Use 
/m4/5elect_object5/window_l  to  specify  that  this  object  is  to  appear  in  the  left  window.  Then 
select  this  object  off. 

3)  create  the  second  image.  You  don’t  have  to  make  this  image  into  an  object  and  specify 
window  2  (although  that  would  work)  because  that  is  where  it  will  go  Ity  default 
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Note  that  if  an  object  and  an  image  are  both  sent  to  the  display  window,  the  object  will  have  pieoedmce 
over  the  image.  &lect  all  objects  off  to  reveal  the  image.  The  current  image  (the  last  one  created)  can 
be  toggled  separately  using  /m4Amage_on/off. 


8.0  SCREEN  FORMATS  (MODULE  5)  AND  SCREEN  DUMPS 

Module  S  aUows  one  to  change  the  format  of  the  display  window  and  of  the  text  ports.  The  main 
options  are: 

/m5/axis  •  This  is  the  set  of  orthogonal  x,y,z  line  segments  that  are  normally 

drawn  at  the  origin.  One  can  vary  the  length  of  the  lines  and  displace 
them. 

/mS/display  -  This  option  enables  one  to  change  the  size  and  location  of  the  main 

display  window.  (This  must  be  toggled  on  with  /toggles/modify_display 
on  the  INDIGO.) 

/mS/text_port  -  Various  options  for  formatting  text  in  the  text  port  inside  of  the  main 

display  window. 

/m5/info_port  -  Various  options  for  formatting  text  in  the  information  port 

/m5;5nfo_box  -  Various  options  for  drawing  an  outline  box  within  the  information 

port 

/m5/title  •  This  displays  the  caption  line  that  is  read  in  off  the  node  data  file. 

One  can  change  the  position,  color  and  borders. 

/m5/grid_units  -  This  allows  one  to  print  out  the  axis  length  in  units  of  KM.  One  can 

modify  the  position  and  color  of  this  captioit 

/mS/legend  -  Allows  one  to  change  the  position  and  size  of  the  color  legmid 

See  Appendix  B  for  a  description  of  the  available  text  ports.  These  must  be  switdied  on  to  see  the 
effects  of  modifications. 

Once  one  has  an  acceptable  screen  view  it  is  possible  to  dump  it  onto  an  image  file  which  can  be  picked 
up  later  (post-IRMA)  and  manipulated  with  the  window  manager.  There  are  three  screen  dump  options: 

1)  /toggles/*  *screen_dump  -  this  dumps  the  entire  screen  (not  available  on  the  INDIGO) 

2)  /toggles/*  *dispiay_dump  •  this  dumps  only  the  image  in  the  displ^  window 
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3)  /toggles/*'*zbu^r_and_dump  -  this  is  the  same  as  the  display  dump,  but  must  be  used 
with  zbufEered  images  (see  Appendix  E) 

When  a  screen  dump  option  is  toggled  on,  there  will  be  a  pause  of  a  few  seconds,  and  then  some  noise 
lines  will  cross  the  screen  on  the  IRIS  3030,  which  signals  that  the  dump  is  complete.  A  line  of  print 
is  written  to  confirm  the  dump.  The  output  files  will  be  called  framel,  frame2  etc.  Any  existing  files 
of  the  same  name  will  be  overwritten. 

To  put  an  image  frame  onto  the  screen,  outside  of  IRMA,  use  the  SI  image  tool  routine  ipaste’.  The 
image  can  then  be  pushed,  popped  and  moved  (but  not  reshaped)  like  any  other  window.  Other  image 
tool  routines  that  are  useful  are: 

clip  •  allows  one  to  extract  a  subimage  from  an  existing  image 

snap  -  allows  one  to  save  an  existing  image  onto  an  image  file 

cedit  •  edit  the  color  map 

mag  -  allows  one  to  scale  up  a  image 

movie  •  shows  a  sequence  of  frames 

These  routines  are  found  in  the  IRMA  subdirectory  /irmafiles/mextools. 

We  have  used  IRMA  and  the  image  tools  on  the  IRIS  3030  to  create  a  movie  to  represent  the  time 
sequence  of  a  SOCRATES  plume  simulation.  The  steps  required  to  do  this  are  outliiied  below: 

1)  run  SOCRATES  at  successive  time  intervals  and  write  the  IRMA  input  node  data  files 

2)  use  IRMA  to  create  image  frames  for  integi'ated  column  density  at  sequential  time 
increments  and  dump  the  image  frames 

3)  use  the  IRMA  text  port  capability  to  create  suitable  header  frames 

4)  coimect  the  RGB  output  of  the  IRIS  to  an  encoder  and  the  encoder  output  to  a  tape 
recorder. 

5)  switch  the  IRIS  signal  to  NTSC  mode  (using  the  SI  setmonitor  command)  and  run  and 
record  the  movie 

Using  this  procedure,  we  have  created  a  short  movie  consisting  of  about  50  image  frames  that  depict  the 
time  development  of  a  shuttle  plume  for  ram,  perpendicular,  and  wake  engine  bums. 

On  the  INDIGO,  we  have  used  the  IRIS  SHOWCASE  program  to  generate  the  header  frames. 


16 


9.0  COLUMN  INTEGRATION 


In  Older  to  calculate  emissions  from  a  distribution  of  molecules  in  space  it  is  necessary  to  int^rate  along 
the  line  of  sight  to  obtain  the  associated  column  densities.  IRMA  has  an  option  to  do  this  cakulatkm 
for  an  arbitrary  observer  viewpoint.  This  option  has  been  used  in  the  analysis  of  SCXltATES  simulation 
results  for  space  shuttle  plumes.  The  algorithm  proceeds  as  follows: 

1)  given  the  current  view  parameters  (either  window  or  ortho),  the  front  dipping  plane  is 
gridded  uniformly  to  form  transverse  area  elements. 

2)  A  ray  from  the  eye  to  the  center  of  each  area  element  is  pushed  from  die  front  to  back 
clipping  plane  and  the  integrated  sum  is  accumulated  and  saved. 

3)  When  all  the  rays  have  been  integrated,  the  column  density  for  each  area  element  is 
gouraud  shaded  and  then  projected  onto  the  back  clipping  plane. 

To  activate  this  calculadon,  use  the  /m3/*create_coiumns  pop  up  menu  option.  One  should  line  up  the 
observers  viewpoint  so  that  the  region  of  data  is  dosely  framed  by  the  clipping  planes  (one  can  use  the 
clipping  mode  to  determine  this). 

Some  aspects  of  the  calculation  are  given  below.  Let  f(x,y,z)  represent  the  source  distribution.  Let  a,b 
denote  die  transverse  coordinates  in  the  front  dipping  plane  and  the  variable  c  stand  for  the  distance 
along  a  line  of  sight  through  point  (a,b),  between  the  front  and  back  clipping  planes.  Then  the  coluiim 
density  at  (a,b)  will  be  given  by 

d(a,b)  =  2  Kw)  dc 

where  the  coordinates  x,y,z  are  determined  by  the  mapping  of  (a,b,c)  onto  the  grid  coordinates  (x,y,z): 


X  =  x(a,b,c) 
y  *  y(a,b,c) 
z  =  z(a,b,c) 

As  c  is  stepped,  the  points  (x,y,z)  do  not  usually  fall  right  on  a  grid  node,  and  the  algorithm  uses 
trilinear  interpolation  in  each  grid  box  to  assign  a  data  value.  If  the  point  (x,y,z)  lies  outside  the  grid, 
zero  is  assigned. 

In  this  calculation,  the  resolution  can  be  varied  by  setting  integers  nab  and  nc  such  that 

da  *  (a2*al)/nab 
db  “  (b2-bl)/nab 
dc  =  (c2-cl)/nc 
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where  denote  the  boundaries  set  by  the  clipping  planes.  The  column  resolution  may  be  set  with  the 
/in3/set_columns  menu  option  (upper  limit  of  SO).  For  32  by  32  by  32  resolution,  the  calculation  typically 
takes  a  little  over  a  minute  on  the  IRIS  3030. 


As  indicated  in  Section  7.0,  the  column  rays  through  the  front  clipping  planes  can  be  displayed  so  one 
can  obtain  a  feeling  for  whether  more  resolution  is  needed.  Some  numerical  details  of  the  calculation 
are  available  through  the  /*/info^age_calc  menu  option.  For  example,  this  prints  out  the  total  intensity 
in  the  viewing  window 


t  -  Z  d(a,b)  da  db  *  E  f(x,y,z)  da  db  dc  =  volume  sum 


The  units  for  the  column  density  calculation  can  be  modified  with  the  /m3fimage  units  menu  option. 
The  units  options  assume  the  input  grid  node  data  f(x,y,z)  is  in  units  of  #  events/cn^^ec.  These  are  the 
units  for  reaction  rate  which  are  output  from  SOCRATES.  In  this  case,  the  natural  units  for  column 
density  are  #  events/cm^/sec,  since  the  integration  over  c  cancels  out  one  power  of  lengfii.  Other  units 
are  available.  For  example,  in  order  to  convert  to  units  of  watts/cm^^r  one  needs  to  multiply  by  the 
energy  emitted  per  event,  de,  and  divide  by  4n  for  solid  angle.  Assuming  one  photon  is  released  per 
event  de  »  h(c/l)  where  1  is  the  photon  wavelength,  which  can  be  set  with  the  mouse. 


If  the  units  are  different  than  the  above,  there  is  an  arbitrary  scale  factor  available  to  convert  die  data 
to  any  set  of  units. 
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APPENDIX  A.  COLOR  MAPS  AND  THE  COLOR  LEGEND 


The  colors  for  the  IRIS  can  be  indexed  to  a  color  map  in  the  range  0  to  1023.  The  programmer  can 
build  his  own  map  and  that  will  become  the  system  map  until  someone  rebuilds  it  If  the  system  crashes, 
the  color  map  is  often  corrupted  and  the  color  map  has  to  be  rebuilt  To  display  the  current  color  map, 
toggle  7m3/color_map/show_map’.  The  color  maps  available  are: 

1)  the  normal  map  -  this  map  mixes  blue  with  green  and  green  with  red  to  produce  a 
‘rainbow’  of  colors 

2)  a  shade  map  -  this  map  has  a  rainbow  with  bands  of  color  mixed  from  blade  towards 
white.  It  can  be  used  with  the  depth  cueing  option. 

3)  a  grey  map  -  this  map  runs  from  black  towards  white.  Used  for  black  and  ^diite  hard 
copy. 

4)  a  sawtooth  grey  map  -  this  map  runs  between  black  and  white  in  an  approximate 
sawtooth  pattern.  Used  for  spedal  lighting  effects. 

5)  a  color  band  map.  Test  map  with  different  bands  of  solid  color. 

The  color  map  works  with  the  legend  to  relate  color  to  value.  IRMA  contains  options  to  modify  this 
relation.  The  white  rectangular  box  drawn  on  the  IRMA  color  map  depicts  the  boundaries  of  the 
mapping  function  for  the  legend  i.e.  data  values  are  mapped  into  successive  rows  starting  at  the  lower 
left  comer  and  ending  with  the  upper  right  comer  of  the  box.  The  shape  of  the  box  can  be  dianged 
with  the  /m3/color_map/color_range  and  /m3/color_map//shade_range  options.  Tlie  former  dianges  the 
vertical  boundaries  of  the  box  and  the  latter  the  horizontal  boundaries.  One  can  also  modify  the  legend 
lower  and  upper  data  limits  and  the  number  of  intervals  using  the  /m3/color_map/data_range  option. 

If  the  legend  is  changed,  previously  colored  objects  may  need  to  be  selectivefy  redrawn  (using 
/m3/*re-draw). 

If  one  toggles  the  log/linear  switch,  the  legend  should  reflect  this  change.  This  switch  does  not  currently 
work  with  nested  multi-grids. 

On  the  INDIGO,  the  legend  can  be  displayed  vertically  using  /toggles/legend_horA«r. 
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APPENDIX  B.  TEXT  PORTS 


Suppose  one  has  set  up  an  acceptable  view  and  is  ready  to  produce  a  hard  copy.  At  this  point  it  may 
be  desirable  to  add  an  informative  caption  of  some  kind.  In  IRMA  one  can  do  this  by  opening  the  text 
port  There  are  two  main  types  of  text  port; 

1)  the  primary  text  port  -  this  port  is  opened  within  the  main  display  window,  at  the  top. 
To  enter  it,  type ‘t’  on  the  keyboard.  The  textport  box  should  then  appear  on  the  screen 
at  the  top  of  the  display  window.  The  keyboard  is  automatically  set  to  text  input  mode. 
This  should  be  indicated  in  the  upper  right  comer  box  (in  set  up  mode). 

2)  the  secondary  (information)  port  •  this  port  opens  a  new  window.  Thus,  it  can  be 
located  anywhere  on  the  screen  and  be  of  arbitrary  size.  Otherwise  it  is  similar  to  the 
primary  port.  There  is  some  added  flexibility  in  that  an  interior  box  for  outlining  text 
can  be  defined.  Use  his  port  when  there  is  a  lot  of  elaborate  information  to  be 
displayed.  To  enter  it,  type  ‘i’.  The  port  window  opens  up  over  the  display  window  and 
is  in  text  input  mode. 

When  in  the  text  input  mode,  a  small  blue  cursor  will  be  visible  within  the  text  port  window.  Any  keys 
that  are  struck  will  type  directly  into  the  text  port  to  the  left  of  the  cursor.  There  is  a  primitive  editor 
in  IRMA  that  allows  one  to  modify  the  text  port.  The  cursor  can  be  moved  by  means  of  the  arrow  kQ^ 
or  with  the  backspace  key  and  the  space  bar.  To  exit  the  text  input  mode,  type  ‘escape’. 

The  text  ports  can  be  modified  using  the  formatting  module  (5).  Things  that  can  be  modified  are  listed 
below: 


a)  The  text  port  can  be  repositioned  on  the  screen 

b)  The  size  of  the  port  can  be  reduced  or  expanded  either  horizontally  or  vertically. 

c)  The  text,  border  and  background  colors  can  be  changed. 

d)  The  number  of  lines  within  the  port  can  be  modified.  Up  to  30  lines  are  allowed.  Line 
markers  can  be  inserted. 

e)  Text  may  be  shifted  horizontally  within  the  port. 

Text  port  information  is  saved  on  the  IRMA  parameter  file  and  so  can  be  recovered  later. 

There  also  exists  a  one  line  text  port  which  allows  one  to  insert  captions  above  the  color  legend.  This 
can  be  used  to  specify  special  sets  of  units.  Type  ‘u’  to  enter  this  port.  The  cursor  works  here  and  the 
line  can  be  edited. 

The  text  ports  can  be  turned  on  and  off  from  the  toggles  menu. 
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APPENDIX  C  DATA  SCANS 


It  is  possible  in  IRMA  to  inspect  selected  node  data  points  from  within  the  graphics  modules.  Tim 
option  can  be  used  to  help  clarify  the  situation,  if  the  graphics  output  doesn’t  look  quite  right  There 
are  currently  three  ways  to  do  this; 

1)  toggle  /^/info/coordinates  -  this  will  list  the  current  grid  coordinates  and  the  data  values 
at  the  listed  points. 

2)  toggle  /*/inf6/probe  •  This  function  uses  Vm3/set_nodes’  to  vary  the  position  of  a  small 
probe  (a  parallelepiped)  that  appears  on  the  screen.  For  example,  set  grid  node  indexes 
i  j,k  to  values  within  the  grid  range,  to  specify  a  point  at  location  x(i),  y(j),  z(k).  The 
color  of  the  probe  will  correspond  to  the  data  value  at  the  node.  The  size  of  the  probe 
is  that  of  a  half-width  cell,  centered  on  the  node.  The  data  value  and  the  oonesponding 
color  index  at  the  node  is  printed  in  the  information  box  at  the  left  (in  set  up  mode). 

3)  toggle  /*/info/grid_scan  -  This  brings  up  a  one  dimensional  line  profile  dirough  the  data. 
Use  Vm3/set_nodes’  to  pick  the  desired  scan  line.  This  is  done  be  setting  to  zero  the 
node  index  of  the  ‘floating’  dimension  to  be  scanned.  For  example,  to  see  the  data  as 
a  function  of  y,  with  x  and  z  held  fixed,  set  the  y  coordinate  indn  j  »  0  and  die  x  and 
z  indexes  i,k  to  fixed  values  so  that  the  coordinates  x(i),  z(k)  lie  within  the  grid 
boundaries. 

By  means  of  these  scan  options  it  is  possible  to  look  at  any  point  in  the  grid. 

A  quick  way  to  obtain  a  ‘global’  view  of  the  data  is  to  build  the  grid  as  an  colored  object  ming 
/m3/*_create _grids.  Each  node  will  then  be  represented  by  a  color  coded  dot  with  the  color 
corresponding  to  the  local  node  value. 
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APPENDIX  D.  MDLU-GRIDS 


Multi-grid  data  can  be  of  two  types. 

1)  Data  for  two  different  variables  existing  on  two  independent  grids. 

2)  Data  for  the  same  variable  existing  on  one  or  more  nested  grids. 

In  order  to  handle  both  types  of  data  we  have  implemented  a  flexible  system,  where  one  can  display  the 
grids  separately  or  one  can  nest  them. 

a)  For  independent  grids  (case  1  above)  the  /m3/select.^d  option  can  be  used  to  select  one 
grid  as  the  current  grid.  All  subsequent  object  creation  will  then  be  based  on  that  grid 
variable. 

b)  For  true  multi-grids  (case  2  above)  that  require  nesting,  use  the  /m3/5elect_grid  option 
to  choose  any  combination  of  grids.  Then  toggle  on  the  /m3/define_i^t  menu  entry. 
This  will  create  a  nesting  function  so  that  any  objects  that  are  subsequently  created  are 
nested  with  respect  to  all  grids  selected  on.  One  can  enable  or  disable  the  nesting 
function  with  the  Vm3/seiectjgrid/nest  on/off  toggle.  Nested  grids  can  be  viewed  by  using 
the  7m3/*aeate.^d_nodes’  option.  If  the  input  nested  grids  do  not  align  on  the 
boundaries,  it  is  possible  to  pad  out  (with  linear  interpolates)  the  inner  grids  so  that  tii^ 
fit  together  with  no  gaps. 

The  nesting  function  works  as  follows.  The  seleaed  grids  are  looped  through,  starting  with  the  lowest 
grid.  At  each  node  a  test  is  made  to  determine:  what  is  the  highest  grid  that  contains  this  node.  This 
number  defines  a  nesting  function  for  each  grid.  In  subsequent  graphics  creation  options  (for 
clouds,slices,levels,  etc.),  the  grids  are  again  looped  over  and  the  nesting  fimction  is  used  at  each  node 
-  if  the  nesting  function  is  not  equal  to  the  current  grid,  then  the  drawing  action  is  skipped.  In  this  way 
the  volume  of  the  computational  grid  is  partitioned  in  such  a  way  that  in  any  cell  the  highest  level  grid 
is  always  used.  Note  that  this  algorithm  will  only  work  the  nested  grids  are  read  in  sequence  from 
course  (lowest  grid  number)  to  fine  (highest  number).  If  two  nested  grids  have  the  same  resolution  and 
th^  overlap,  the  one  with  the  higher  grid  number  will  predominate  in  the  shared  region. 

This  section  is  still  in  development. 
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APPENDIX  E.  ZBUFFER 


When  IRMA  draws  polygonal  objects  it  normally  starts  with  the  first  polygon  in  the  list  and  draws  than 
in  order.  If  the  first  polygon  is  in  the  background  (i.e.  furthest  the  observer)  fiiis  causes  no 
problem.  But  if  the  first  polygon  in  the  list  is  in  the  foreground,  then  it  can  subsequent^  get  drawn  over 
by  polygons  behind  it,  leading  to  a  confusing  picture  where  the  true  orientation  and  structure  of  the 
object  may  be  obscured.  This  problem  can  be  fixed  by  using  the  Silicon  Graphics  ZBUFFBR  option, 
which  enables  one  to  shadow  out  hidden  surfaces.  It  works  by  testing  the  z  coordinate  of  eadi  pizd  and 
only  drawing  the  pixel  with  the  z  value  nearest  to  the  observer. 

On  the  3030  workstation  the  zbuffer  process  is  slow  and  is  not  done  continuously.  In  IRMA  lliere  is 
a  /toggles/zbufEer  switch  that  can  be  used  to  zbuffer  any  fixed  view.  The  screen  remains  in  the  zbufEered 
state  until  the  next  event  in  the  queue  is  encountered  (This  could  be  a  mouse  dick  or  any  kq^board 
event).  The  screen  then  reverts  back  to  normal.  Note  that  one  must  be  in  disph^  mode  in  order  for 
the  zbuffer  option  to  work  (only  one  window  can  be  open).  The  zbuffer  switch  can  also  be  activated 
from  the  keyboard  by  typing  a  ‘d’  to  go  to  display  mode  and  a  ‘z*  to  turn  on  the  dnifEer.  On  foe 
INDIGO,  zbu^r  can  be  on  continuously. 

The  zbuffer  option  does  not  represent  lines  embedded  in  a  polygon  surface  property  (the  ‘decal*  problem) 
because  it  cannot  distinguish  between  two  pixels  with  the  same  z  value.  Thus  any  lines  lying  rigfit  on 
a  surface  can  tend  to  look  fragmented.  To  work  around  this  problem  we  have  added  an  option  to  IRMA 
(accessed  firom  /m3/modify/split_wire_frame)  to  split  the  wire  fiame  outline  of  eadr  polygon  surface  so 
foat  two  fiames  are  drawn,  each  displaced  plus  and  minus  epsilon  (user  specified)  along  the  normal  to 
foe  polygon.  This  separates  slightly  the  z  coordinate  of  the  wire  frame  lines  from  that  of  the  surface 
polygon  and  makes  the  lines  more  visible  during  zbuffering. 

The  depth  cueing  option  switch  in  IRMA  is  subject  to  the  same  constraints  as  zbuffer.  It  maps  color 
with  z  depth  and  can  be  used  with  the  shade  map  to  make  near  lines  appear  brighter  and  for  lines  to 
have  decreased  intensity.  This  option  has  not  been  used  much. 
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APPENDIX  F.  PROGRAMMING  NOTES 


The  IRMA  program  consists  of  a  mixture  of  C  and  fortran  coding.  There  are  approximately  2SK  lines 
of  source  cc^  of  which  60%  is  in  FORTRAN.  Assembly  language  wrappers  provide  entry  point 
interfaces  for  FORTRAN-C  calls.  The  main  program  is  in  FORTRAN  and  most  of  tbe  graphks  code 
is  in  C  The  code  uses  the  Silicon  graphics  multiple  windowing  capability  (mex  on  the  IRIS  303, 4Dwm 
on  the  INDIGO)  to  manage  up  to  10  windows.  The  executable  iBle  ‘irma’  is  located  in  directory  ^ima 
along  with  many  sample  input  files.  The  directory  /irma  has  a  number  of  subdirectorws.  This  directory 
tree  contains  all  the  code  needed  to  compile  and  link  IRMA. 

The  source  routines  and  object  files  are  located  in  subdirectory  /src.  To  update  the  eucutable,  tsrpe 
‘make’  in  this  directory.  This  will  automatically  remake  the  wrappers  and  files  with  modified  indudes. 
The  linker  references  two  archive  libraries: 

1)  /npltools  -  this  contains  routines  needed  to  use  the  MSIO  files,  borrowed  finm  NPLDES 
program. 

2)  /mextools  -  this  contains  SI  image  tools  needed  to  do  screen  dumps  and  to  manijnilate  the 
image  files  that  are  produced. 

The  include  files  are  in  subdirectory  Anc  The  file  irmas.h  contains  important  size  parameters.  The 
grap.h  and  grap_ext.h  files  hold  the  C  commons  variables.  Some  of  the  other  .h  are  SI  ^tem  files,  put 
here  so  that  IRMA  is  self-contained  (except  for  one  proprietary  file  geth). 

The  FORTRAN  to  C  (f2c)  and  C  to  FORTRAN  (c2f)  wrapper  scripts  are  in  subdirectory  Avrapper.  To 
remake  a  wrapper  by  hand  Q^pe: 

.Twrapper/wrapfc  name  (for  FORTRAN  TO  Q 
.Twrapper/wrapcf  name  (for  C  to  FORTRAN) 

Here  ‘name’  is  the  source  file  name  without  extension.  Normally  you  don’t  have  to  do  this  (make  does 
it  all).  However,  the  construction  of  the  wrapper  files  is  describ^  by  these  scripts.  There  are  examples 
for  both  c2f  and  £2c  wrappers  in  /src.  A  ‘£2c’  routine  will  be  recognized  by  its  having  three  files:  name.c, 
name.o,  and  name.fc  A  ‘c2f  routine  will  also  have  three  files:  name.!,  name.o  and  name.cl 

The  help  files  are  in  subdirectory  /help. 

The  source  code  for  constructing  utilities  for  handling  MSIO  files  are  in  subdirectory  /mstook. 

The  preliminary  INDIGO  version  of  IRMA  is  functionally  the  same  as  the  IRIS  3030  version.  The 
main  differences  are  summarized  below. 

1)  The  wrapper  routines  are  done  differently.  The  FORTRAN  to  C  routines  are  handled  the 
same,  but  the  C  to  FORTRAN  wrappers  are  changed.  To  call  a  FORTRAN  routine  from  C, 
you  append  an  underscore  to  the  routine  name  and  all  arguments  are  passed  by  reference  (by 
placing  an  ampersand  in  front  of  each  argument) 
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2)  You  no  longer  have  to  be  in  display  mode  to  turn  on  the  z  buffer.  And  the  z  buffer  worts 
while  an  object  is  being  moved,  instead  of  toggling  off  immediately  with  the  detection  of  ai^ 
queue  event 

3)  The  windows  are  much  more  flexible,  since  they  can  be  moved  and  resized  using  the  41>wm 
control  bar  menus.  The  display  mode  is  still  active,  but  it  simply  dears  away  die  status  and  slider 
bar  windows  and  does  not  modify  the  display  window. 

4)  There  is  a  test  ‘zrgb’  option  in  the  toggles  menu  viuch  enables  one  to  enter  a  graphics  state 
that  is  double  buffered,  z  buffered  and  is  in  rgb  color  mode.  This  option  will  not  be  supported 
on  all  machines.  To  exit  this  mode,  hit  the  ‘escape’  key. 

5)  There  is  an  enhanced  Makefile  in  directory  /irma.  Type  ‘make’  in  this  directory  and  all 
required  source  files  will  be  compiled  and  linked,  induding  the  external  libraries. 

6)  The  SOCRATES  binary  files  ( RST)  can  be  read  from  within  irma.  The  source  code  for 
this  option  is  in  directory  /socplot. 
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APPENDIX  G.  SAMPLE  PLOTS 


The  following  plots  give  a  sample  of  the  IRMA  capabilities. 

Plot  1  (Figure  1):  The  IRMA  set  up  mode  configuration. 

Plot  2  (Figure  2):  The  POLAR  code  model  of  the  DMSP  satellite. 

Plot  3  (Figure  3):  The  integrated  column  density  for  a  SOCRATES  simulation  of  a  perpendicular 

bum  of  the  RCS  engines. 

Plot  4  (Figure  4):  The  POLAR  code  depiction  of  the  plasma  sheath  arouml  foe  SPEAR  lodcet 

The  curved  line  represents  an  electron  trajectory. 
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Figure  1.  The  IRMA  set  up  mode  configuration.  Hie  POLAR  micro  shuttle  model  is  in  the  display  window. 
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Figure  2.  The  POLAR  code  model  of  the  DMSP  satellite.  The  colored  coded  surfaces  represent  surface  charging. 
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Figure  3.  The  integrated  column  density  for  a  SOCRATES  simulation  of  a  perpendicular  bum  of  the  RCS  engines. 


used  to  produce  the  forward  light  shading. 


